<div class="content">

  <h1>Logging & Debugging</h1>

  <section>
    <p class="wide">
      Upgrading to 5.0.0? Read the <a [routerLink]="['/migrate500']" simplePageScroll href="#navigation">migration notes</a>.
    </p>
  </section>

  <section class="toc">
    <ul>
      <li><a simplePageScroll href="#section-debug-mode">Logging emails instead of sending</a></li>
      <li><a simplePageScroll href="#section-debug-logging">Enable javax.mail debug logging</a></li>
      <li><a simplePageScroll href="#section-inspect-mailer-email">Inspect a mailer or an email</a></li>
      <li><a simplePageScroll href="#section-mailexception">Catching exceptions</a></li>
      <li><a simplePageScroll href="#section-logging">Logging output</a></li>
      <li><a simplePageScroll href="#section-log4j12" class="indent">Example with log4j12</a></li>
      <li><a simplePageScroll href="#section-log4j2" class="indent">Example with log4j2</a></li>
      <li><a simplePageScroll href="#section-logback" class="indent">Example with logback</a></li>
    </ul>
  </section>


  <a href="#section-debug-mode" id="section-debug-mode" class="section-link h2">&sect;</a>
  <h2>Logging emails instead of sending</h2>

  <section>
    <div class="view">
      <p>
        You can configure the <code>Mailer</code> to log emails instead of sending them.
      </p>
      <p>
        Note: normally emails are always logged on <code>Level.DEBUG</code> level, but in logging mode emails are logged in <code>Level.INFO</code>.
      </p>
    </div>

    <div class="side">
<pre><code>Mailer mailer = MailerBuilder
    .(...)
    .withTransportModeLoggingOnly()
    .buildMailer();

mailer.sendMail(email); // <-- this email will be logged but not sent
</code></pre>
      or:
      <pre><code class="language-properties">simplejavamail.transport.mode.logging.only=true
</code></pre>
    </div>
  </section>


  <a href="#section-debug-logging" id="section-debug-logging" class="section-link h2">&sect;</a>
  <h2>Enable javax.mail debug logging</h2>

  <section>
    <div class="view">
      <p>
        By default javax.mail's debug logging is turned off, but you can turn it on for more diagnostic info. All this does is enabling debug mode on
        the internal Session instance.
      </p>
    </div>

    <div class="side">
<pre><code>MailerBuilder.withDebugLogging();

// or
mailer.getSession().setDebug(true);

// or
yourSession.setDebug(true);
MailerBuilder.usingSession(yourSession);
</code></pre>
      or:
      <pre><code class="language-properties">simplejavamail.javaxmail.debug=true
</code></pre>
    </div>
  </section>


  <a href="#section-debug-logging" id="section-inspect-mailer-email" class="section-link h2">&sect;</a>
  <h2>Inspect a mailer or an email</h2>

  <section>
    <div class="view">
      <p>
        After building a Mailer or an Email instance, you can read some details back from it and see if it is what you expected.
      </p>
    </div>

    <div class="side">
<pre><code>email.getAnythingYouCanSetWithABuilder();

mailer.getSession();
mailer.getTransportStrategy();
mailer.getServerConfig();
mailer.getProxyConfig();
mailer.getOperationalConfig();
mailer.getEmailAddressCriteria();
</code></pre>
    </div>
  </section>


  <a href="#section-mailexception" id="section-mailexception" class="section-link h2">&sect;</a>
  <h2>Catching exceptions</h2>

  <section>
    <div class="view">
      <p>
        Simple Java Mail throws a <code class="inline">MailException</code> if something goes wrong and logs these by default using SLF4J. This
        includes checked exceptions thrown by underlying frameworks. An exception might be thrown when:
      </p>
      <ul class="indent">
        <li>creating an email</li>
        <li>creating a mailer</li>
        <li>sending an email</li>
        <li>signing an email with DKIM</li>
        <li>validating an address</li>
        <li>converting an email between various types</li>
      </ul>
    </div>

    <div class="side">
<pre><code>
try {{ '{' }}
   mailer.sendMail(email);
{{ '}' }} catch (MailException e) {{ '{' }}
   // handle the exception
{{ '}' }}
</code></pre>
    </div>
  </section>

  <a href="#section-logging" id="section-logging" class="section-link h2">&sect;</a>
  <h2>Logging output</h2>

  <section>
    <div class="view">
      <p>
        Simple Java Mail uses <a href="http://www.slf4j.org/">SLF4J</a> to log, which means you can use any logging framework you like that supports
        it. Also read this excellent summary of <a href="http://learnjava-soa.blogspot.nl/2015/06/slf4j-with-log4j2-example.html">how to configure
                                                                                                                                  slf4j with
                                                                                                                                  log4j2</a>.
      </p>
      <div>
        Aside from the native JavaMail logging, there are three parts of Simple Java Mail that may produce logging:
        <ul class="indent">
          <li>"org.simplejavamail"</li>
          <li>"socks5bridge"</li>
          <li>"org.simplejavamail.mailer.internal.socks"</li>
        </ul>
        <p>The latter two are for the proxy bridge that is used for <a [routerLink]="['/proxy']" simplePageScroll href="#navigation">authenticated
                                                                                                                                     proxy
                                                                                                                                     connections</a>.
        </p>
      </div>
      <p>
        If you wish to know where and how the properties are loaded, you can increase logging for "org.simplejavamail.util.ConfigLoader".
        This will tell you which properties are loaded by API and which from config file and which properties are without value.
      </p>
      <p>
        When using maven, Simple Java Mail provides some default XML configuration for log4j2, but you can easily switch to something else. Below are
        some examples.
      </p>
    </div>
  </section>

  <a href="#section-log4j12" id="section-log4j12" class="section-link h3">&sect;</a>
  <h3>Example with log4j12</h3>

  <section>
    <div class="view">
      <p>
        Here's an example configuration for <a href="http://logging.apache.org/log4j/2.x/index.html">log4j12</a>, make sure you have the
        slf4j-to-log4j impl included on the classpath as well as log4j12 itself and the log4j.xml with the config.
      </p>
    </div>

    <div class="side">
<pre><code class="language-markup small">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE log4j:configuration SYSTEM &quot;log4j.dtd&quot;&gt;
&lt;log4j:configuration xmlns:log4j=&quot;http://jakarta.apache.org/log4j/&quot; debug=&quot;false&quot;&gt;

    &lt;appender name=&quot;console&quot; class=&quot;org.apache.log4j.ConsoleAppender&quot;&gt;
        &lt;layout class=&quot;org.apache.log4j.PatternLayout&quot;&gt;
            &lt;param name=&quot;ConversionPattern&quot; value=&quot;%d [%t] %-5p %c{{ '{' }}1{{ '}' }} - %m%n&quot;/&gt;
        &lt;/layout&gt;
    &lt;/appender&gt;
    &lt;appender name=&quot;simpleConsole&quot; class=&quot;org.apache.log4j.ConsoleAppender&quot;&gt;
        &lt;layout class=&quot;org.apache.log4j.PatternLayout&quot;&gt;
            &lt;param name=&quot;ConversionPattern&quot; value=&quot;%d Simple Java Mail SOCKS5 bridge - %p %m%n&quot;/&gt;
        &lt;/layout&gt;
    &lt;/appender&gt;

    &lt;logger name=&quot;org.simplejavamail&quot;&gt;
        &lt;level value=&quot;trace&quot;/&gt;
        &lt;appender-ref ref=&quot;console&quot;/&gt;
    &lt;/logger&gt;
    &lt;!-- in case you&#39;re using authenticated proxy --&gt;
    &lt;logger name=&quot;socks5bridge&quot; additivity=&quot;false&quot;&gt;
        &lt;level value=&quot;info&quot;/&gt;
        &lt;appender-ref ref=&quot;simpleConsole&quot;/&gt;
    &lt;/logger&gt;
    &lt;logger name=&quot;org.simplejavamail.mailer.internal.socks&quot;&gt;
        &lt;level value=&quot;warn&quot;/&gt;
    &lt;/logger&gt;

&lt;/log4j:configuration&gt;
</code></pre>
    </div>
  </section>

  <a href="#section-log4j2" id="section-log4j2" class="section-link h3">&sect;</a>
  <h3>Example with log4j2</h3>

  <section>
    <div class="view">
      <p>
        Here's an example configuration for <a href="http://logging.apache.org/log4j/2.x/">log4j2</a>, make sure you have the log4j-slf4j-impl impl
        included on the classpath as well as log4j2 itself and the log4j2.xml with the config.
      </p>
    </div>

    <div class="side">
<pre><code class="language-markup small">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;configuration status=&quot;OFF&quot;&gt;
    &lt;appenders&gt;
        &lt;Console name=&quot;console&quot; target=&quot;SYSTEM_OUT&quot;&gt;
            &lt;PatternLayout pattern=&quot;%d{{ '{' }}HH:mm:ss{{ '}' }} [%t] %-5level %c{{ '{' }}1{{ '}' }} - %msg%n&quot; /&gt;
        &lt;/Console&gt;
        &lt;Console name=&quot;simpleConsole&quot; target=&quot;SYSTEM_OUT&quot;&gt;
            &lt;PatternLayout pattern=&quot;%d Simple Java Mail SOCKS5 bridge - %level %m%n&quot; /&gt;
        &lt;/Console&gt;
    &lt;/appenders&gt;
    &lt;Loggers&gt;
        &lt;Logger name=&quot;org.simplejavamail&quot; level=&quot;trace&quot;/&gt;
        &lt;!-- in case you&#39;re using authenticated proxy --&gt;
        &lt;Logger name=&quot;socks5bridge&quot; level=&quot;info&quot; additivity=&quot;false&quot;&gt;
            &lt;AppenderRef ref=&quot;simpleConsole&quot; /&gt;
        &lt;/Logger&gt;
        &lt;Logger name=&quot;org.simplejavamail.mailer.internal.socks&quot; level=&quot;warn&quot;/&gt;

        &lt;Root level=&quot;warn&quot;&gt;
            &lt;AppenderRef ref=&quot;console&quot; /&gt;
        &lt;/Root&gt;
    &lt;/Loggers&gt;
&lt;/configuration&gt;
</code></pre>
    </div>
  </section>

  <a href="#section-logback" id="section-logback" class="section-link h3">&sect;</a>
  <h3>Example with logback</h3>

  <section>
    <div class="view">
      <p>
        Here's an example configuration for <a href="http://logback.qos.ch/">logback</a>, make sure you have the logback-classic included on the
        classpath as well as logback-core and the logback.xml with the config.
      </p>
    </div>

    <div class="side">
<pre><code class="language-markup small">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;configuration&gt;
    &lt;appender name=&quot;console&quot; class=&quot;ch.qos.logback.core.ConsoleAppender&quot;&gt;
        &lt;encoder&gt;
            &lt;pattern&gt;%d{{ '{' }}HH:mm:ss.SSS{{ '}' }} [%thread] %-5level %c{{ '{' }}1{{ '}' }} - %msg%n&lt;/pattern&gt;
        &lt;/encoder&gt;
    &lt;/appender&gt;
    &lt;appender name=&quot;simpleConsole&quot; class=&quot;ch.qos.logback.core.ConsoleAppender&quot;&gt;
        &lt;encoder&gt;
            &lt;pattern&gt;%d Simple Java Mail SOCKS5 bridge - %level %m%n&lt;/pattern&gt;
        &lt;/encoder&gt;
    &lt;/appender&gt;

    &lt;logger name=&quot;org.simplejavamail&quot; level=&quot;TRACE&quot;/&gt;
    &lt;!-- in case you&#39;re using authenticated proxy --&gt;
    &lt;logger name=&quot;socks5bridge&quot; level=&quot;INFO&quot; additivity=&quot;false&quot;&gt;
        &lt;appender-ref ref=&quot;simpleConsole&quot; /&gt;
    &lt;/logger&gt;
    &lt;logger name=&quot;org.simplejavamail.mailer.internal.socks&quot; level=&quot;WARN&quot;/&gt;

    &lt;root level=&quot;WARN&quot;&gt;
        &lt;appender-ref ref=&quot;console&quot; /&gt;
    &lt;/root&gt;
&lt;/configuration&gt;
</code></pre>
    </div>
  </section>

</div>
